home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / src / linux-headers-2.6.28-15 / include / net / iucv / iucv.h < prev   
Encoding:
C/C++ Source or Header  |  2008-12-24  |  13.9 KB  |  416 lines
  1. /*
  2.  *  drivers/s390/net/iucv.h
  3.  *    IUCV base support.
  4.  *
  5.  *  S390 version
  6.  *    Copyright 2000, 2006 IBM Corporation
  7.  *    Author(s):Alan Altmark (Alan_Altmark@us.ibm.com)
  8.  *        Xenia Tkatschow (xenia@us.ibm.com)
  9.  *    Rewritten for af_iucv:
  10.  *    Martin Schwidefsky <schwidefsky@de.ibm.com>
  11.  *
  12.  *
  13.  * Functionality:
  14.  * To explore any of the IUCV functions, one must first register their
  15.  * program using iucv_register(). Once your program has successfully
  16.  * completed a register, it can exploit the other functions.
  17.  * For furthur reference on all IUCV functionality, refer to the
  18.  * CP Programming Services book, also available on the web thru
  19.  * www.vm.ibm.com/pubs, manual # SC24-6084
  20.  *
  21.  * Definition of Return Codes
  22.  * - All positive return codes including zero are reflected back
  23.  *   from CP. The definition of each return code can be found in
  24.  *   CP Programming Services book.
  25.  * - Return Code of:
  26.  *   -EINVAL: Invalid value
  27.  *   -ENOMEM: storage allocation failed
  28.  */
  29.  
  30. #include <linux/types.h>
  31. #include <asm/debug.h>
  32.  
  33. /*
  34.  * IUCV option flags usable by device drivers:
  35.  *
  36.  * IUCV_IPRMDATA  Indicates that your program can handle a message in the
  37.  *          parameter list / a message is sent in the parameter list.
  38.  *          Used for iucv_path_accept, iucv_path_connect,
  39.  *          iucv_message_reply, iucv_message_send, iucv_message_send2way.
  40.  * IUCV_IPQUSCE      Indicates that you do not want to receive messages on this
  41.  *          path until an iucv_path_resume is issued.
  42.  *          Used for iucv_path_accept, iucv_path_connect.
  43.  * IUCV_IPBUFLST  Indicates that an address list is used for the message data.
  44.  *          Used for iucv_message_receive, iucv_message_send,
  45.  *          iucv_message_send2way.
  46.  * IUCV_IPPRTY      Specifies that you want to send priority messages.
  47.  *          Used for iucv_path_accept, iucv_path_connect,
  48.  *          iucv_message_reply, iucv_message_send, iucv_message_send2way.
  49.  * IUCV_IPSYNC      Indicates a synchronous send request.
  50.  *          Used for iucv_message_send, iucv_message_send2way.
  51.  * IUCV_IPANSLST  Indicates that an address list is used for the reply data.
  52.  *          Used for iucv_message_reply, iucv_message_send2way.
  53.  * IUCV_IPLOCAL      Specifies that the communication partner has to be on the
  54.  *          local system. If local is specified no target class can be
  55.  *          specified.
  56.  *          Used for iucv_path_connect.
  57.  *
  58.  * All flags are defined in the input field IPFLAGS1 of each function
  59.  * and can be found in CP Programming Services.
  60.  */
  61. #define IUCV_IPRMDATA    0x80
  62. #define IUCV_IPQUSCE    0x40
  63. #define IUCV_IPBUFLST    0x40
  64. #define IUCV_IPPRTY    0x20
  65. #define IUCV_IPANSLST    0x08
  66. #define IUCV_IPSYNC    0x04
  67. #define IUCV_IPLOCAL    0x01
  68.  
  69. /*
  70.  * iucv_array : Defines buffer array.
  71.  * Inside the array may be 31- bit addresses and 31-bit lengths.
  72.  * Use a pointer to an iucv_array as the buffer, reply or answer
  73.  * parameter on iucv_message_send, iucv_message_send2way, iucv_message_receive
  74.  * and iucv_message_reply if IUCV_IPBUFLST or IUCV_IPANSLST are used.
  75.  */
  76. struct iucv_array {
  77.     u32 address;
  78.     u32 length;
  79. } __attribute__ ((aligned (8)));
  80.  
  81. extern struct bus_type iucv_bus;
  82. extern struct device *iucv_root;
  83.  
  84. /*
  85.  * struct iucv_path
  86.  * pathid: 16 bit path identification
  87.  * msglim: 16 bit message limit
  88.  * flags: properties of the path: IPRMDATA, IPQUSCE, IPPRTY
  89.  * handler:  address of iucv handler structure
  90.  * private: private information of the handler associated with the path
  91.  * list: list_head for the iucv_handler path list.
  92.  */
  93. struct iucv_path {
  94.     u16 pathid;
  95.     u16 msglim;
  96.     u8  flags;
  97.     void *private;
  98.     struct iucv_handler *handler;
  99.     struct list_head list;
  100. };
  101.  
  102. /*
  103.  * struct iucv_message
  104.  * id: 32 bit message id
  105.  * audit: 32 bit error information of purged or replied messages
  106.  * class: 32 bit target class of a message (source class for replies)
  107.  * tag: 32 bit tag to be associated with the message
  108.  * length: 32 bit length of the message / reply
  109.  * reply_size: 32 bit maximum allowed length of the reply
  110.  * rmmsg: 8 byte inline message
  111.  * flags: message properties (IUCV_IPPRTY)
  112.  */
  113. struct iucv_message {
  114.     u32 id;
  115.     u32 audit;
  116.     u32 class;
  117.     u32 tag;
  118.     u32 length;
  119.     u32 reply_size;
  120.     u8  rmmsg[8];
  121.     u8  flags;
  122. };
  123.  
  124. /*
  125.  * struct iucv_handler
  126.  *
  127.  * A vector of functions that handle IUCV interrupts. Each functions gets
  128.  * a parameter area as defined by the CP Programming Services and private
  129.  * pointer that is provided by the user of the interface.
  130.  */
  131. struct iucv_handler {
  132.      /*
  133.       * The path_pending function is called after an iucv interrupt
  134.       * type 0x01 has been received. The base code allocates a path
  135.       * structure and "asks" the handler if this path belongs to the
  136.       * handler. To accept the path the path_pending function needs
  137.       * to call iucv_path_accept and return 0. If the callback returns
  138.       * a value != 0 the iucv base code will continue with the next
  139.       * handler. The order in which the path_pending functions are
  140.       * called is the order of the registration of the iucv handlers
  141.       * to the base code.
  142.       */
  143.     int  (*path_pending)(struct iucv_path *, u8 ipvmid[8], u8 ipuser[16]);
  144.     /*
  145.      * The path_complete function is called after an iucv interrupt
  146.      * type 0x02 has been received for a path that has been established
  147.      * for this handler with iucv_path_connect and got accepted by the
  148.      * peer with iucv_path_accept.
  149.      */
  150.     void (*path_complete)(struct iucv_path *, u8 ipuser[16]);
  151.      /*
  152.       * The path_severed function is called after an iucv interrupt
  153.       * type 0x03 has been received. The communication peer shutdown
  154.       * his end of the communication path. The path still exists and
  155.       * remaining messages can be received until a iucv_path_sever
  156.       * shuts down the other end of the path as well.
  157.       */
  158.     void (*path_severed)(struct iucv_path *, u8 ipuser[16]);
  159.     /*
  160.      * The path_quiesced function is called after an icuv interrupt
  161.      * type 0x04 has been received. The communication peer has quiesced
  162.      * the path. Delivery of messages is stopped until iucv_path_resume
  163.      * has been called.
  164.      */
  165.     void (*path_quiesced)(struct iucv_path *, u8 ipuser[16]);
  166.     /*
  167.      * The path_resumed function is called after an icuv interrupt
  168.      * type 0x05 has been received. The communication peer has resumed
  169.      * the path.
  170.      */
  171.     void (*path_resumed)(struct iucv_path *, u8 ipuser[16]);
  172.     /*
  173.      * The message_pending function is called after an icuv interrupt
  174.      * type 0x06 or type 0x07 has been received. A new message is
  175.      * availabe and can be received with iucv_message_receive.
  176.      */
  177.     void (*message_pending)(struct iucv_path *, struct iucv_message *);
  178.     /*
  179.      * The message_complete function is called after an icuv interrupt
  180.      * type 0x08 or type 0x09 has been received. A message send with
  181.      * iucv_message_send2way has been replied to. The reply can be
  182.      * received with iucv_message_receive.
  183.      */
  184.     void (*message_complete)(struct iucv_path *, struct iucv_message *);
  185.  
  186.     struct list_head list;
  187.     struct list_head paths;
  188. };
  189.  
  190. /**
  191.  * iucv_register:
  192.  * @handler: address of iucv handler structure
  193.  * @smp: != 0 indicates that the handler can deal with out of order messages
  194.  *
  195.  * Registers a driver with IUCV.
  196.  *
  197.  * Returns 0 on success, -ENOMEM if the memory allocation for the pathid
  198.  * table failed, or -EIO if IUCV_DECLARE_BUFFER failed on all cpus.
  199.  */
  200. int iucv_register(struct iucv_handler *handler, int smp);
  201.  
  202. /**
  203.  * iucv_unregister
  204.  * @handler:  address of iucv handler structure
  205.  * @smp: != 0 indicates that the handler can deal with out of order messages
  206.  *
  207.  * Unregister driver from IUCV.
  208.  */
  209. void iucv_unregister(struct iucv_handler *handle, int smp);
  210.  
  211. /**
  212.  * iucv_path_alloc
  213.  * @msglim: initial message limit
  214.  * @flags: initial flags
  215.  * @gfp: kmalloc allocation flag
  216.  *
  217.  * Allocate a new path structure for use with iucv_connect.
  218.  *
  219.  * Returns NULL if the memory allocation failed or a pointer to the
  220.  * path structure.
  221.  */
  222. static inline struct iucv_path *iucv_path_alloc(u16 msglim, u8 flags, gfp_t gfp)
  223. {
  224.     struct iucv_path *path;
  225.  
  226.     path = kzalloc(sizeof(struct iucv_path), gfp);
  227.     if (path) {
  228.         path->msglim = msglim;
  229.         path->flags = flags;
  230.     }
  231.     return path;
  232. }
  233.  
  234. /**
  235.  * iucv_path_free
  236.  * @path: address of iucv path structure
  237.  *
  238.  * Frees a path structure.
  239.  */
  240. static inline void iucv_path_free(struct iucv_path *path)
  241. {
  242.     kfree(path);
  243. }
  244.  
  245. /**
  246.  * iucv_path_accept
  247.  * @path: address of iucv path structure
  248.  * @handler: address of iucv handler structure
  249.  * @userdata: 16 bytes of data reflected to the communication partner
  250.  * @private: private data passed to interrupt handlers for this path
  251.  *
  252.  * This function is issued after the user received a connection pending
  253.  * external interrupt and now wishes to complete the IUCV communication path.
  254.  *
  255.  * Returns the result of the CP IUCV call.
  256.  */
  257. int iucv_path_accept(struct iucv_path *path, struct iucv_handler *handler,
  258.              u8 userdata[16], void *private);
  259.  
  260. /**
  261.  * iucv_path_connect
  262.  * @path: address of iucv path structure
  263.  * @handler: address of iucv handler structure
  264.  * @userid: 8-byte user identification
  265.  * @system: 8-byte target system identification
  266.  * @userdata: 16 bytes of data reflected to the communication partner
  267.  * @private: private data passed to interrupt handlers for this path
  268.  *
  269.  * This function establishes an IUCV path. Although the connect may complete
  270.  * successfully, you are not able to use the path until you receive an IUCV
  271.  * Connection Complete external interrupt.
  272.  *
  273.  * Returns the result of the CP IUCV call.
  274.  */
  275. int iucv_path_connect(struct iucv_path *path, struct iucv_handler *handler,
  276.               u8 userid[8], u8 system[8], u8 userdata[16],
  277.               void *private);
  278.  
  279. /**
  280.  * iucv_path_quiesce:
  281.  * @path: address of iucv path structure
  282.  * @userdata: 16 bytes of data reflected to the communication partner
  283.  *
  284.  * This function temporarily suspends incoming messages on an IUCV path.
  285.  * You can later reactivate the path by invoking the iucv_resume function.
  286.  *
  287.  * Returns the result from the CP IUCV call.
  288.  */
  289. int iucv_path_quiesce(struct iucv_path *path, u8 userdata[16]);
  290.  
  291. /**
  292.  * iucv_path_resume:
  293.  * @path: address of iucv path structure
  294.  * @userdata: 16 bytes of data reflected to the communication partner
  295.  *
  296.  * This function resumes incoming messages on an IUCV path that has
  297.  * been stopped with iucv_path_quiesce.
  298.  *
  299.  * Returns the result from the CP IUCV call.
  300.  */
  301. int iucv_path_resume(struct iucv_path *path, u8 userdata[16]);
  302.  
  303. /**
  304.  * iucv_path_sever
  305.  * @path: address of iucv path structure
  306.  * @userdata: 16 bytes of data reflected to the communication partner
  307.  *
  308.  * This function terminates an IUCV path.
  309.  *
  310.  * Returns the result from the CP IUCV call.
  311.  */
  312. int iucv_path_sever(struct iucv_path *path, u8 userdata[16]);
  313.  
  314. /**
  315.  * iucv_message_purge
  316.  * @path: address of iucv path structure
  317.  * @msg: address of iucv msg structure
  318.  * @srccls: source class of message
  319.  *
  320.  * Cancels a message you have sent.
  321.  *
  322.  * Returns the result from the CP IUCV call.
  323.  */
  324. int iucv_message_purge(struct iucv_path *path, struct iucv_message *msg,
  325.                u32 srccls);
  326.  
  327. /**
  328.  * iucv_message_receive
  329.  * @path: address of iucv path structure
  330.  * @msg: address of iucv msg structure
  331.  * @flags: flags that affect how the message is received (IUCV_IPBUFLST)
  332.  * @buffer: address of data buffer or address of struct iucv_array
  333.  * @size: length of data buffer
  334.  * @residual:
  335.  *
  336.  * This function receives messages that are being sent to you over
  337.  * established paths. This function will deal with RMDATA messages
  338.  * embedded in struct iucv_message as well.
  339.  *
  340.  * Returns the result from the CP IUCV call.
  341.  */
  342. int iucv_message_receive(struct iucv_path *path, struct iucv_message *msg,
  343.              u8 flags, void *buffer, size_t size, size_t *residual);
  344.  
  345. /**
  346.  * iucv_message_reject
  347.  * @path: address of iucv path structure
  348.  * @msg: address of iucv msg structure
  349.  *
  350.  * The reject function refuses a specified message. Between the time you
  351.  * are notified of a message and the time that you complete the message,
  352.  * the message may be rejected.
  353.  *
  354.  * Returns the result from the CP IUCV call.
  355.  */
  356. int iucv_message_reject(struct iucv_path *path, struct iucv_message *msg);
  357.  
  358. /**
  359.  * iucv_message_reply
  360.  * @path: address of iucv path structure
  361.  * @msg: address of iucv msg structure
  362.  * @flags: how the reply is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST)
  363.  * @reply: address of data buffer or address of struct iucv_array
  364.  * @size: length of reply data buffer
  365.  *
  366.  * This function responds to the two-way messages that you receive. You
  367.  * must identify completely the message to which you wish to reply. ie,
  368.  * pathid, msgid, and trgcls. Prmmsg signifies the data is moved into
  369.  * the parameter list.
  370.  *
  371.  * Returns the result from the CP IUCV call.
  372.  */
  373. int iucv_message_reply(struct iucv_path *path, struct iucv_message *msg,
  374.                u8 flags, void *reply, size_t size);
  375.  
  376. /**
  377.  * iucv_message_send
  378.  * @path: address of iucv path structure
  379.  * @msg: address of iucv msg structure
  380.  * @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST)
  381.  * @srccls: source class of message
  382.  * @buffer: address of data buffer or address of struct iucv_array
  383.  * @size: length of send buffer
  384.  *
  385.  * This function transmits data to another application. Data to be
  386.  * transmitted is in a buffer and this is a one-way message and the
  387.  * receiver will not reply to the message.
  388.  *
  389.  * Returns the result from the CP IUCV call.
  390.  */
  391. int iucv_message_send(struct iucv_path *path, struct iucv_message *msg,
  392.               u8 flags, u32 srccls, void *buffer, size_t size);
  393.  
  394. /**
  395.  * iucv_message_send2way
  396.  * @path: address of iucv path structure
  397.  * @msg: address of iucv msg structure
  398.  * @flags: how the message is sent and the reply is received
  399.  *       (IUCV_IPRMDATA, IUCV_IPBUFLST, IUCV_IPPRTY, IUCV_ANSLST)
  400.  * @srccls: source class of message
  401.  * @buffer: address of data buffer or address of struct iucv_array
  402.  * @size: length of send buffer
  403.  * @ansbuf: address of answer buffer or address of struct iucv_array
  404.  * @asize: size of reply buffer
  405.  *
  406.  * This function transmits data to another application. Data to be
  407.  * transmitted is in a buffer. The receiver of the send is expected to
  408.  * reply to the message and a buffer is provided into which IUCV moves
  409.  * the reply to this message.
  410.  *
  411.  * Returns the result from the CP IUCV call.
  412.  */
  413. int iucv_message_send2way(struct iucv_path *path, struct iucv_message *msg,
  414.               u8 flags, u32 srccls, void *buffer, size_t size,
  415.               void *answer, size_t asize, size_t *residual);
  416.